docs/examples/State Estimation Example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "89cf2628",
   "metadata": {},
   "source": [
    "(ex_state_est)=\n",
    "# State Estimation Example\n",
    "\n",
    "In this notebook we will walk through an example of state estimation calculation of `power-grid-model`.\n",
    "The following points are covered\n",
    " * Construction of the model\n",
    " * Run state estimation once, and its relevant function arguments\n",
    "\n",
    "\n",
    "It serves an example of how to use the Python API. For detailed API documentation, refer to\n",
    "[Python API reference](../api_reference/python-api-reference.md)\n",
    "and [Native Data Interface](../advanced_documentation/native-data-interface.md).\n",
    "\n",
    "\n",
    "## Example Network\n",
    "\n",
    "We use a simple network with 3 nodes, 1 source, 3 lines, and 2 loads. As shown below:\n",
    "\n",
    "```\n",
    " -----------------------line_8---------------\n",
    " |                                          |\n",
    "node_1 ---line_3--- node_2 ----line_5---- node_6\n",
    " |                    |                     |\n",
    "source_10          sym_load_4           sym_load_7\n",
    "```\n",
    "\n",
    "The 3 nodes are connected in a triangular way by 3 lines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ae11dc9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# some basic imports\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "from power_grid_model import LoadGenType\n",
    "from power_grid_model import PowerGridModel, CalculationMethod, CalculationType\n",
    "from power_grid_model import initialize_array"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f983cef7",
   "metadata": {},
   "source": [
    "## Input Dataset\n",
    "\n",
    "We create input dataset by using the helper function `initialize_array`.\n",
    "Note the units of all input are standard SI unit without any prefix,\n",
    "i.e. the unit of voltage is volt (V), not kV.\n",
    "\n",
    "Please refer [Components](../user_manual/components.md) for detailed explanation of all component types and their input/output attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "6f008736",
   "metadata": {},
   "outputs": [],
   "source": [
    "# node\n",
    "node = initialize_array(\"input\", \"node\", 3)\n",
    "node[\"id\"] = [1, 2, 6]\n",
    "node[\"u_rated\"] = [10.5e3, 10.5e3, 10.5e3]\n",
    "\n",
    "# line\n",
    "line = initialize_array(\"input\", \"line\", 3)\n",
    "line[\"id\"] = [3, 5, 8]\n",
    "line[\"from_node\"] = [1, 2, 1]\n",
    "line[\"to_node\"] = [2, 6, 6]\n",
    "line[\"from_status\"] = [1, 1, 1]\n",
    "line[\"to_status\"] = [1, 1, 1]\n",
    "line[\"r1\"] = [0.25, 0.25, 0.25]\n",
    "line[\"x1\"] = [0.2, 0.2, 0.2]\n",
    "line[\"c1\"] = [10e-6, 10e-6, 10e-6]\n",
    "line[\"tan1\"] = [0.0, 0.0, 0.0]\n",
    "line[\"i_n\"] = [1000, 1000, 1000]\n",
    "\n",
    "# load\n",
    "sym_load = initialize_array(\"input\", \"sym_load\", 2)\n",
    "sym_load[\"id\"] = [4, 7]\n",
    "sym_load[\"node\"] = [2, 6]\n",
    "sym_load[\"status\"] = [1, 1]\n",
    "sym_load[\"type\"] = [LoadGenType.const_power, LoadGenType.const_power]\n",
    "sym_load[\"p_specified\"] = [20e6, 10e6]\n",
    "sym_load[\"q_specified\"] = [5e6, 2e6]\n",
    "\n",
    "# source\n",
    "source = initialize_array(\"input\", \"source\", 1)\n",
    "source[\"id\"] = [10]\n",
    "source[\"node\"] = [1]\n",
    "source[\"status\"] = [1]\n",
    "source[\"u_ref\"] = [1.0]\n",
    "\n",
    "# voltage sensor\n",
    "sym_voltage_sensor = initialize_array(\"input\", \"sym_voltage_sensor\", 3)\n",
    "sym_voltage_sensor[\"id\"] = [11, 12, 13]\n",
    "sym_voltage_sensor[\"measured_object\"] = [1, 2, 6]\n",
    "sym_voltage_sensor[\"u_sigma\"] = [1.0, 1.0, 1.0]\n",
    "sym_voltage_sensor[\"u_measured\"] = [10489.37, 9997.32, 10102.01]\n",
    "\n",
    "# power sensor\n",
    "sym_power_sensor = initialize_array(\"input\", \"sym_power_sensor\", 8)\n",
    "sym_power_sensor[\"id\"] = [14, 15, 16, 17, 18, 19, 20, 21]\n",
    "sym_power_sensor[\"measured_object\"] = [3, 3, 5, 5, 8, 8, 4, 7]\n",
    "sym_power_sensor[\"measured_terminal_type\"] = [0, 1, 0, 1, 0, 1, 4, 4]\n",
    "sym_power_sensor[\"power_sigma\"] = [1.0e3, 1.0e3, 1.0e3, 1.0e3, 1.0e3, 1.0e3, 1.0e3, 1.0e3]\n",
    "sym_power_sensor[\"p_measured\"] = [1.73e07, -1.66e07, -3.36e06, 3.39e06, 1.38e07, -1.33e07, 20e6, 10e6]\n",
    "sym_power_sensor[\"q_measured\"] = [4.07e06, -3.82e06, -1.17e06, 8.86e05, 2.91e06, -2.88e06, 5e6, 2e6]\n",
    "\n",
    "# all\n",
    "input_data = {\n",
    "    \"node\": node,\n",
    "    \"line\": line,\n",
    "    \"sym_load\": sym_load,\n",
    "    \"source\": source,\n",
    "    \"sym_voltage_sensor\": sym_voltage_sensor,\n",
    "    \"sym_power_sensor\": sym_power_sensor,\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "157db2f0",
   "metadata": {},
   "source": [
    "## Validation (optional)\n",
    "For efficiency reasons, most of the data is not explicitly validated in the power grid model. However, in most cases, a state estimation will fail/crash if the data is invalid. Often with a low level error message that is hard to relate to the original objects. Therfore, it is recommended to always validate your data before constructing a PowerGridModel instance.\n",
    "\n",
    "The simplest and most effective way to validate your data is by using `assert_valid_input_data()` which will throw an error if it encounters any invalid data. See [Validation Examples](Validation%20Examples.ipynb) for more detailed information on the validation functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "fab31f58",
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model.validation import assert_valid_input_data\n",
    "assert_valid_input_data(input_data=input_data, calculation_type=CalculationType.state_estimation)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "afae0224",
   "metadata": {},
   "source": [
    "## Construction\n",
    "\n",
    "The construction of the model is just calling the constructor of `PowerGridModel`. The default `system_frequency` is 50.0 Hz.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "7ef134e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "model = PowerGridModel(input_data)\n",
    "# model = PowerGridModel(input_data, system_frequency=60.0)  # if you have another system frequency"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3605c3e",
   "metadata": {},
   "source": [
    "## One-time State Estimation Calculation\n",
    "\n",
    "You can call the method `calculate_state_estimation` to do a one-time state estimation calculation based on the current network data in the model. In this case you should not specify the argument `update_data` as it is used for batch calculation.\n",
    "\n",
    "The following command executes a one-time state estimation calculation with (they are also the default values for those arguments)\n",
    "* Symmetric calculation\n",
    "* Iterative linear method\n",
    "* Error tolerance: 1e-8\n",
    "* Maximum number of iteration: 20."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "44c2de63",
   "metadata": {},
   "outputs": [],
   "source": [
    "output_data = model.calculate_state_estimation(\n",
    "    symmetric=True,\n",
    "    error_tolerance=1e-8,\n",
    "    max_iterations=20,\n",
    "    calculation_method=CalculationMethod.iterative_linear)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d08aaf45",
   "metadata": {},
   "source": [
    "### Result Dataset\n",
    "\n",
    "We can also print one result dataset of node and line by converting the array to dataframe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "a581a36e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------node result------\n",
      "   id  energized      u_pu             u   u_angle\n",
      "0   1          1  0.998922  10488.678869  0.000000\n",
      "1   2          1  0.952157   9997.648144 -0.022921\n",
      "2   6          1  0.962132  10102.384509 -0.018780\n",
      "------line result------\n",
      "   id  energized   loading        p_from        q_from      i_from  \\\n",
      "0   3          1  0.983446  1.731816e+07  4.068528e+06  979.232855   \n",
      "1   5          1  0.206048 -3.367751e+06 -1.178575e+06  206.048359   \n",
      "2   8          1  0.780866  1.381050e+07  2.916091e+06  776.961713   \n",
      "\n",
      "         s_from          p_to          q_to        i_to          s_to  \n",
      "0  1.778965e+07 -1.659573e+07 -3.820392e+06  983.446244  1.702978e+07  \n",
      "1  3.568023e+06  3.398729e+06  8.860393e+05  200.729011  3.512325e+06  \n",
      "2  1.411500e+07 -1.335538e+07 -2.885123e+06  780.865585  1.366346e+07  \n"
     ]
    }
   ],
   "source": [
    "print(\"------node result------\")\n",
    "print(pd.DataFrame(output_data[\"node\"]))\n",
    "print(\"------line result------\")\n",
    "print(pd.DataFrame(output_data[\"line\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e516b436",
   "metadata": {},
   "source": [
    "## Observability\n",
    "\n",
    "In order to perform a state estimation the number of measurements should be larger than or equal to the number of unknowns. For each node there are two unknowns: `u` and `u_angle`.\n",
    "\n",
    "$$n_{\\text{measurements}} >= n_{\\text{unknowns}}$$\n",
    "\n",
    "Where\n",
    "\n",
    "$$n_{\\text{unknowns}} = 2 n_{\\text{nodes}} $$\n",
    "\n",
    "And\n",
    "\n",
    "$$n_{\\text{measurements}} = n_{\\text{nodes_with_voltage_sensor_without_angle}} + 2 n_{\\text{nodes_with_voltage_sensor_with_angle}} + 2 n_{\\text{branches_with_power_sensor}} + 2 n_{\\text{nodes_without_any_appliances_connected}} + 2 n_{\\text{nodes_with_all_connected_appliances_measured_by_power_sensor}}$$\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3da1f2aa",
   "metadata": {},
   "source": [
    "## Batch calculation\n",
    "\n",
    "For state estimation a batch calculation can be performed in a similar manner as for powerflow calculations. For more information about performing a batch calculation, please refer to the [Power Flow Example](./Power%20Flow%20Example.ipynb#Batch-Calculation)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.13 ('pgm-dev')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  },
  "vscode": {
   "interpreter": {
    "hash": "39f035c5e58f53e973c1999fdd4393d6db2dd3f04fe05f524988f90f4bbdb576"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}